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I /iO/y^S d/s Mrl^C- 4^ ^^. /-^Asi/^ 



This document attempts to do several things. There is a proposed conceptual 

structure for the Tools Group programs. There is a lot of proposini] of names for 

things. There is a section that proposes solutions for several of the major problem 

**s 

that we have encountered. I also go through some of the structure piece by piece 

and list all the defficiences I have been able to think of. This is an attempt at a 

**n 

exhaustive list of deff iciencies . For many of the pieces I propose some changes to 

the current interfaces and implementations. 

It should be noted that most of the proposed changes are not due to real 
defficiences, but are usually ideas that I or others have had about better ways to 
do things. None of the proposed changes should be taken as inferring that 
anybody has been guilty. of bad design work. A lot of the ideas came from using 
the existing software and then thinking of ways it might be changed to make it 
easier or smoother to use. There are some proposed deletions of some code that 
experience has indicated would rarely be used. There are a bunch of minor 
"cleanup" things suggested. 

It should also be noted that everything in this document is intended as a proposal 
-- to be discussed and debated by the group prior to approval or rejection.- I have 
not often included some phrase like "I propose" or "I suggest" in the document. I 
hope everyone will take all of the ideas stated in here as if there were such a 
phrase somewhere in the discussion of the idea. 

I have not had time to put all this material into a nice, formal memo form. Please 
bear with all the rough edges that are in here. I'll try to smooth it out later. I 

have not had time to write down all my reasons and justifications for the proposed 
changes. I would like to present those verbally. 

I suggest that we all spend Wednesday afternoon doing something like the 

following: Go through the document and decide which things we will do and 

which we won't. For those things that we decide to do, decide when, e.g., for the 

Preview Release, as soon as possible after that, "eventually". For those things tha 

**t 

are to be done soon, we should decide who is to do them. 



xerox' SDD AKCHIVES 
I have read and understood 
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Reviewer 
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John Weaver proposes the term ''Development Environment" to mean all the 
software listed below (m large part written by the Tools Group vnth some major 
help from others on things like the guts of the Compiler Sersier; several of the 
tools will probably be written by others also). 



The Development Environment is made up of three pieces: the "Tools 
Environment", a collection of "tools", and several "servers". 

The Tools Environment is mode up of 6 pieces: the module Telnit that constructs 

the Tools Environment (an image file), the configuration that is the "Tools 

Executive", and 4 configurations that are "packages" of subroutines or "interfaces", 
** 

The four interfaces are: the User Interface, the Librarian Interface, the Fifo 
Interface, and the Pup Package (including FTP). 



Here is the hierarchical structure of the DeveVopment Environment (with 
abbreviations): 



Tools Environment (TE or Te) 

Telnit 

Tools Executive (TEX or Tex) -- TexDefs 

TexStimLev 

TexProcLev 

TexBackLev 

TexQueue 

TexManipTools 

TexTool 

User Interface (UI or Ui) ~- UiDefs 

UiDisplay 

UiFonts 

UiWindowBasics and UiWindowContents 

UiMenus and UiMenuCS 

UiSelections 

UiCursors 

UiUAS 

UiMisc 

UiContexts 

Librarian Interface (LibI or Libi) -- LibiDefs 

LibiObjects 
LibiPropLists 

Fifo Interface (Fifol or Fifoi) -- FifoiDefs 

??? 

Pup Package -- PupDefs 
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Servers 



Librarian Server 

Fifo Server 

File Store 

Compi ler Server 

Xref Server 

Info Server 

Printer Server(s) -- EARS, 3100, etc. 

Source Formatter Server 

Tools 

Local Librarian 

Examine 

Typescript 

Program Editor 

General Editor 

Compiler 

Spooler 

Message 

Chat 

Debugger(s) 

Conf iguror 

Dynamic Program Analyzer 

Cursor Editor 

various project management tools 

various testing tools 



The following things should be noted about the pieces and names above: 

The Tools Environment is basically all the code that lives in one of the 
Tools. image files (but doesn't inc^lude the Mesa Runtime System). 

The module Telnit has no corresponding Defs file. The files TexDefs and 
UiDefs have no implementors. The module TexTool includes the Window 
Manager. The modules UiWindowBasics and UiWindowContents both 
implement the Defs file UiWindowDef s . The modules UiMenus and UiMenuCS 
(Menu Command Select) may get combined into just one UiMenus. The 
modules LibiObjects and LibiPropLists implement LibiDefs and have no other 
corresponding Defs files. The same situation will probably hold true for the 
Fifo Interface module(s). There are a whole lot of modules that implement 
PupDefs. All the other modules in the TE have exactly one Defs file that they 
implement. The Pup Package was not written by the Tools Group. 

I'm not greatly attached to the particular spellings of the prefixes Tex, Ui, Libi 

and Fifoi, but I do think it very important that each of the files that make up 
a configuration or interface all start with the same short prefix. I also think 
that lumping all the modules listed above into the User Interface is a good idea. 

I'm not greatly attached to any of the server names. The File Store will not be 
done by the Tools Group. The Librarian Sevyer, Fifo Server, and the File Store 
will each have exactly one dedicated machine (but we may want to run both 
the Librarian and Fifo Servers in the same machine). There may be zero or 
several instances of the other servers at any particular time. The compiler part 
of the Compiler Server will not be written by the Tools Group. The Info Server 
is my name for something that would perform functions like the current Lister 
and/or Simonyi's CR programs (or maybe this should all be combined into a 
more general Xref Server). The Source Formatter is the "Procedures and 
Standards" name for the program that makes Mesa source code files conform to 
the standards. The above list of servers is probably not exhaustive. 
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I'm not greatly attached to any of the too! names. Therp may he no' need to 
have all of the Examine, TypeScript, Program Editor, and General Editor Tools 
a$ separate tools since they are so similar. The General Editor (probably 
Diamond) may never be implemented as a tool. The Compiler lool should be 
ar;le to»-do a s.ingte? local conipilation and do a "consistent" compilation of some 
group of modules either locally or via a Compiler Server. The Spooler Tool is 
my idea ior one tool that could set things up for any of the Xref, Info, Printer, 
or Source rormatter Servers (or any other "data processing" servers there may 
be). The Message Tool vnll probably be mostly written by Metcalf's group. 
The Chat tool may be written by Schwartz. The Debugger Tool(s) assumes the 
existence of a "Core Debugger". The Configuror assumes the existence of 
"configurations". The various project management and testing tools will 
probably .not be written by the Tools Group. 

I think it is very important for us (the Tools Group) to agree on some such 
conceptual structure as the above and to agree on the names of things. I think 
this would be a great aid in our thinking, our communications with each other, 
and in our documentation. I think an agreement on (what I have called) the 
Tools Environment's structure and names should be settled on very soon. I think 
we can leave the names and even the existence some of the tools and servers a 
little vague for a while longer. 
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Here are some proposed solutions to problems that currently exist: 

How does a PNR or MCR retain control while a PBK is held down? 

I propose the following routine that will live in TexProcLev: 

IsPbKStillDown: PROCEDURE [TexDef s . PBK] RETURNS [BOOLEAN]; 

Each time the routine- is called, it will go through the User Action Queue, 
looking for the appropriate down PBK item. It will throw away all items 
(including the looked-for item) until the queue is empty or the item is found 
(this merely means that no PNRs will be called). The returned BOOLEAN tells 
(the converse of) whether the item was found. Each call will do the right 
thing so that subsequent calls on GetProcLevCursorPosition will return the 
right thing -- that*'s the hardware coordinates of the cursor if the PBK is still 
down, or the coordinates in the looked-for queue item if the PBK just went up. 

In both cases the coordinates returned are a BitmapPlace and have been 
corrected for the hot spot. 

What to do about subwindow boundary crossings with PBKs held down? 

I propose the following routine that will live in TexProcLev: 

EnumerateDownPBKs: PROCEDURE [UiDefs,PNRsHandle, TexDef s .UpDown]; 

The idea is that cursor PNRs could call this routine if they wanted to warn 

their tool about down PBKs when the subwindow was being entered or exited. 

This routine would go through the Processing Level state (NOT the Stimulus . 

Level state) looking for PBKs that were down and call the appropriate PNR if it 

found one. Note that the PNRs will always be called with the UpDown 

specified above. This is so, e.g., the cursor PNR can fool its PNRs into thinking 

the PBKs went down on entry into the subwindow but went up on exit. Note 
also that the cursor PNR may just' want to use the standard PNRs of its 
subwindow, or it may use another set of PNRs for this sort of thing (and 
possibly different PNRs for entering and exiting). Note also that if the 
subwindow isn't interested in some of the PBKs, it is free to use 
UiMiscDefs.NopPbkPNR in any of the fields of the PNRsObject. 

What to do about the cursor "hot spot" problem? 

I think the thing to do is to change the cursor package so that any time a 
StoreCursor or SwapCursor is done, the hardware cursor and mouse coordinates 
get changed according to the. relative differences of the old and new hot spots. 
Note that interrupts should be turned off when changing the hardware 
coordinates. 

The cursor may jump a little bit, but users should be told that the hot spot will 
track smoothly. Note that this scheme follows our convention that the user 
must predict what the situation will be if he/she types ahead. I think it's 
actually easy for the user. I think he/she need merely always point at things 
with the hot spot of whatever cursor is currently on the screen. 

About image files: 

I think that there are at least 8 different image files that various people will 
want to have available. (Below, "most Mesa" currently means all Mesa. except 
Keyst.reams. ) 
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Mesa , image • 

all Mesa code segn^nts 

all Mesa symbol seginenis 

PupBare. image 

all Mesa and Pup Package code segments 
no symbols 

PupPared. image 

all Mesa and Pup Package code segments 

an Mesa symbols, but only Coolie's symbols from the Pup Package 

PupAll . image 

all Mesa and Pup Package code segments 
all Mesa and Pup Package symbol segments 

TeBare. image 

most Mesa, all Pup Package, and all TE code segments 
no symbols 

TePared. image 

most Mesa, all Pup Package, and all TE code segments 

most Mesa, but only Coolie's from the Pup Package, and no TE symbols 

TeFul 1 . image 

most Mesa, all Pup Package, and all TE code segments 

most Mesa, but only Coolie's fjrom the Pup Package, and all TE symbols 

TeAll . image 

most Mesa, all Pup Package, and all TE code segments 
most Mesa, all Pup Package,, and all TE symbol segments 

I propose to write the small amount of code required to produce PupPared. image. 

I also propose that someone (probably me) generate each of the files listed 
above. We should keep as many of them as will fit in <Tools> or on IPS. . The 
others may be kept on a disk pack somewhere. 

About selections (and in particular how to get more. than one tool named TestTool 
instantiated) : 

It should be noted that we do NOT currently have a very useful selection 
mechanism. 

I propose a (possibly temporary) solution: Somebody should write a TypeScript 
Tool. TEX would "define" that tool at startup time. Using a UAS, the 
TypeScript Tool would allow type-in. New type-in up to a CR or ESC would 
become the current selection. The tool would also (eventually) have selection 
button PNRs. This seems the quickest way to get type-in to be selected for use 
as parameters to commands (at least to the Instantiate-tool comm^and). 

Note that the tool would be made up almost exclusively of routines that I 

propose for inclusion in UiMisc and UiSelection. This tool could serve as a 

prototype or testbed for those routines before we actually include them in the 
User Interface. 

There may be some problems about bitmaps and turning the display on and off 
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before and after ca-lls on Makelnage. 

I talked to Wick about this a little. Smokey. the three of us should get together 

and make sure we do the right thing 

Here's an idea for which 1 can find no better place in this document: 

It would be nice if the Fifo Server could glom onto any Alto on the Ethernet 

that was running DMT and set up a server there. Boggs and Taft know how 

to do this. Note that such a server would have to do all of its file I/O over the 
** 

Ethernet. . (I 'm not sure I'm the originator of this idea.) 

I would like to take this. opportunity to point out another of our unsolved 
problems, but I have no solutions to propose: 

What, if anything, is the Librarian Server going to do about automatically 
compiling, formatting, printing, xrefing, etc. files as they are checked in? 
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Using my proposed hierarchical structure of the Tools Lnv ironnien t, here are my 
(intermixed) lists of deficiencies and proposed changes. At various points you 
will find listings of some of the Defs files for the User Interface. They should 
help to indicate or explain some of the things I have in mind. 

Some of the proposals below have the "keyword" "done" attached to them. That 

means they've already been done. Some have the keyword "eventually". That 

means I suggest we wait a (long) while before doing them. Some have the 

keyword "sometime". That means I suggest we don't try to do them for the 

Preview Release. I suggest that we try to incorporate all the other proposals (that 
** 

get accepted) in the Preview Release. 



First I would like to talk a bit about the organization of the User Interface 
definitions files. I 'am unable to decide which of several schemes I think is the 
better. I'd like to mull this over with you all. Here are the schemes: 

The scheme proposed in this document which basically just breaks the former 
ToolWindowDefs into UiDefs (typ.es and constants only) and UiWindowDefs 
(the procedures). 

Leave ToolWindowDefs as it is (but rename it UiWindowDefs)* 

Move the Places, Boxes, etc. definitions to TexDefs. 

Treat PNRsObjects as contexts. Note that then the "pnrs" field of 
SubwindowObjects would be deleted. Then we could move all the PNRs 
definitions (including the {Cursor/Pbk}PnrTypes) into their own Defs file. .We 
would then have to provide routines like 

'{I/Uni}nstantiatePNRs{With/From}{W/Subw}indow. Below I have proposed 
that CreateSubwindow take a PWRsHandle parameter. That would have to 
change if this idea is accepted. 

We could make SubwindowObject.contextChain be PRIVATE and of type 
POINTER. Then we could move all the context definitions into UiContextDef s. 
Note that no one except the Contexts package is ever supposed to touch this 
field, so it might not be very dangerous. 
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T e 1 n i f. 

Change name of file from Texlnit to Tel nit. 

Move Unf^ew to Te^.Man1pTools . 

Delete TexInitDefs. 

Move code in Lib jectLoader to this file. 

Load UiDisplay and UiFonts. 

Do the right thing about getting the display initialized. 

Load the Fifo Interface. • 

Get new Pup Package. 

Eventually, move some of the initialization code to TexProcLev so that this 
module and its global frame may be released before the Makelmage. 

Eventually, pare Mesa runtime further. 
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Tools Executive (TEX or Te/) -- TexDefs 

TexDef s 

Wo proposed changes. 

TexStimLev 

Put in the new way of getting to the debugger via a chord. This will 
(usually) leave the debugger pointed at the right frame of the right process. 

Maybe, have the "wiggling bit" problem taken care of by the Stimulus 
rather than the Processing Level. 

Sometime, add abort cho'rd(s). 

Sometime, add "clear User Action Queue" chord. 

TexProcLev 

Query the user as to where the Librarian and Fifo Servers and the File Store 
are. If they are to be on the local machine, then some NBSs must be done. 
In any case, the information has to be conveyed to the appropropiate parties. 

Change so that user actions occuring while the cursor is in a window's • 
frame go to TexTool (assuming that the frame is not in any of the 
subwindows of that window). 

Do an UnNew on Telnlt. 

Add IsPbkStillDown (see the discussion about the problem of PNRs retaining 
control while a PBK is held down). 

The Window Manager is going to need an analagous routine to help with 
the continuous Move commands before the "click" (see below). 

Add EnumerateDownPBKs (see the discussion about the problem of 
subwindow boundary crossings while PBKs are held down). 

Eventually, redo the PNR mechanism using coroutines. 
TexBackLev 

Rename TexBackground{Defs} to be TexBackLev{Defs}. 

Eventually, redo background mechanism using coroutines. 
TexQueue 

No changes proposed. 
TexManipTools 

Move UnNew procedure from Texinit to here. 

Add uas field to ToolInstanceObject. -- see UiUAS discussion 

Add warmStart field to ToolInstanceObject. This is a procedure in each tool 
to be called for "warm starting" tool instances after something like TexTool *s 
Subsys command. . 

TexMisc 

Move the procedures and their definitions to UiMisc. Move some other 
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definitions to TexDefs. Delfte TexMiscfUsf s} . -- done 
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Tr;^1oo1 -- the -Window Mmager is discussed below 

Snokey suggested an iaea anout nakinc] texWindow le a real window. * I'm 
not sure, but I currently thiirK it's s'ligfitiy better the v/ay it is now. 

Add tfiR loliov/ing comnands: Subsys, fJstall. Reset. Checkpoint. See my 
memo ''k'ish List far a Mesa System" tor details and justifications. 

Add a command to turn the Monitor on and off. 

Eventually, add the Kill command. 

Window Manager -- the code will live in TexTool 

I propose the following menu commands: 

Flip 

Move 

Grow 

Tiny 

Normal 

Zoom 

Unzoom 

Permanent-menu-window/Des troy-menu-window (sometime soon) 

Cleanup-screen (sometime soon) 

About Flip: If the indicated window is on top, put it on the bottom, else put 
it on top (or there could be separate Bottom and Ontop commands). 

About Permanent-menu-window/Des troy-menu-window: 

The idea here is to make a "normal" window containing a Ring Menu 
Subwindow (see below) and leave it displayed on the screen, i.e., not just 
while the menu button is heldjjown. 

There's a potential problem here if the user uninstantiates the tool 
containing the MCRs without Destroying the Menu Window. Another 
potential problem is that the Window Manager has no good way of 
knowing which windows are Menu Windows. 

About Cleanup-screen: This is Titleman^s idea about automatically 
straightening out a chaotic screen full of windows (perhaps by making them 
all tiny and distributing them as evenly as possible over the bitmap).. 

Most of the commands above need a (corner of a) window as an operand. I 
propose the following rules for picking the operand. 

If the command is invoked from a window's menu ring, use that 
window's corner that is nearest to the cursor. 

If the command is invoked from TexTool 's menu ring while the cursor is 
in some window's name frame, use that window's nearest (upper left or 
rigtit) corner. 

If the command is invoked from TexTooVs "window", use the "nearest" 
window corner. 

Note that if the command is invoked from a menu, the button will be UP 
when the MCR is called. I suggest that the Flip, Tiny, Normal, Unzoom, 
and Permanent-menu commands turn themselves into Move (continuous) 
commands after doing their thing. Then the user will terminate those 
commands and the Move and Grow commands by "clicking" the menu 
button (or any PBK) which will "deposit" the window and terminate the 
command. 
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Another possible way to do this would he to h?^.ve the ^tser select the 
command in the nornal manner. 7 he the V/indO'.v Manacjer would wait for 
tne nenu button to go liov/n, ihrowiny awRy ail other- user actions. When 
the i)uttGn v/ent -down, the Wii^aow Manager wouln pick a cof , er and 
proceed with the command until the button went up. I think this might be 
a hai^der way to do things. 

I propose that we allocate the mouse button PNRs of TexWindow as follows: 

blue -- normal MenuPbkPnr 

yello.w -- will do the Grow command, with zooming done via running 
the cursor to any of the corners of the screen 

red ~~ will put the window on top and then turn into the Move command 
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User Interface (UI or Ui) -- UIDefs 

Note that all file names will have to be changed if my proposed names are 

accepted. . ■ * . 

UiDefs 

See the attached listing for what this file might look like. I will discuss the 

Coords, etc. section immediately below. The Windows and Subwindows 
sections are discussed in the UiWindow section below. The only change in 
the PNRs section is the order of the parameters for a PbkPnrType -- this one • 
seems more "natural" to me, it is more inkeeping with the sub-standard that 
the "major" abstraction be the first parameter. The Contexts section is 
discussed under UiContexts. 

If the CARDINALity of Dimension necessitates ANY loopholes, it should be 
changed to be an INTEGER. 

The type Coords may well be superfluous. I put it in for completeness and 
symmetry. 

The types ScreenPlace and ScreehBox are meant to be used by UiDisplay 
when dealing with bitmaps. 

The Coord and Dimension types are defined following the reasoning of the 

"sub-standards" that predefined types should be used as little as possible. 

Also note that* if Dimension must be changed to INTEGER, there is only one 
thing to change rather than several. 

I think breaking boxes into places and Dimensions will prove to be a useful 
thing, maybe primarily for clarity of code. There is also the point that 
under the old scheme, one couldn't do something like the following: 
box. place ^ WindowPlaceFromBitmapPlace [...]» """ ^^^ scheme 
[box.x, box.y] *- WindowPlaceFromBitmapPlace [...]» — o^^ scheme 

Note that there are few comments in UiDefs. I think this makes it more 
readable and nobody has to worry about errors in the comments. Also, there 
is now documentation for the stuff here, so the need for comments is greatly 
lessened and there is the potential problem of keeping, two versions of the 
same thing consistent (the comments and the documentation). 
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U1 Display 

Remove MovaOps fron the directory of the impl ef-:entor' . 

Use ScreenPlace and/or ScreenBox from UiDefs. 

The Defs file has a several definitions that 1 would guess are copied from 
Mesa system Defs files, I'm not sure that's a good idea. 
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Ui Fonts 

Remove NovaOps from the directory of the inplenientor . 

Remove MopCodes from the directory of the Oefs file. 

Add the following types: FontHeight CharWidth, StringWidth. 

Define the type FontHandle either instead of or as a synonym for FAptr. 

See the attached Defs file listing for details about most of the above proposed 
changes. 

The Defs file has a several definitions that I would guess are copied from 
Mesa system Defs files. I'm not sure that's a good idea. 
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UiVi indowBasics and UiWindov^Con tents and UiWindovf[)efs 

See the attached listings of UiDefs and UiW )ndow[)ef s for details about a lot 
of the suggestioas discussed belcv/. Note, that these haven't been updated 
yet to reflect ttie laslest changes in the proposals. 

Note that there are tew comments m UiVMndowDets . I think this makes it 
more readable and nobody has to worry about errors in the consents. Also, 
there is nov/ documentation for the stuff here, so the need for comments is 
greatly lessened and there is the potential problem of keeping two versions 
of the same thing consistent (the comments and the documentation). 

I added several types to UiWindowDefs to conform to the sub-standard of 
using predefined types as little as possible and to avoid keywords in calling 
sequences . 

Remove KeyDefs and StreamDefs from the directories. 

Fix bug about window. box ^ box untrimmed to bitmap. 

Fix bug involving MoveWindowContinuous . 

Use UiDisplay and UiFonts. 

A careful check should be made of the Defs versus the implementors to try 
to weed out any remaining discrepancies. 

Add routines Vai idate{W/Subw}indow which would raise the ERRORS 
{W/Subw}indowNotEnl inked when they were called to check parameters to 
other routines. The errors {W/Subw}indowAlreadyEnl inked should also be 
raised under the appropriate circumstances. . 

The Window Manager is going to be the prime, if not the only, user of 
several routines in UiWindowBasics , e.g., MoveWindow. This is because 
tools are not generally supposed to do things like Move or Zoom their 
windows, but rather are to leave that up to the user to do using the Window 
Manager. I designed the Window Manager and then realized that there was 
probably little or no need for some window fields, types, and procedures. 
Here is a list: 

Delete window. size and the' type WindowSizeType. 

Delete the Places from window. {normal/tiny}Box, so they get renamed 
{normal/tiny}Dims and are of type Dimensions. Note that the Window 
Manager commands Tiny and Normal will get the Place from the cursor 
because they turn themselves into a Move command. 

The five routines that changed a window*s size, e.g., 
MakeWindowSizeTiny, all got coalesced into one: GrowWindow. Nate 
that the Window Manager command Zoom will get the window's 
Dimensions from the bitmap's Dimensions. Unzoom, Tiny, and Normal 
can look into the WindowObject to get the Dimensions. 

Note that the tiny and normal parameters to CreateWindow are now 
Dimensions rather than BitmapBoxes. 

In writing a MenuPbkPNR, I discovered that I wanted to specify the INSIDE 

dimensions of the window to CreateWindow. Since I had no easy way of 

knowing the dimensions of the window frame, I couldn't specify the 

OUTSIDE dimensions easily. I would think that a almost all users of 

CreateWindow would rather specify the inside dimensions too. Also, when 

it comes time for a tool to divide up it's window into subwindows, I think' it 

would like to know the space it has to work with, i.e., the inside dimensions, 

But note that it can only use the dimensions of the main subwindow once 
fop this, since the tool will probably shrink that subwindow to make room 
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for others (otherwise it's going to have to deal with ovprlapping 
suDwindows) . (in the other hand, all sorts of routines want to knov^ the 
outside box of a v/indov/, e.g.,. to decide what's visible. I also think that all 
windov/s ought to have frames and naries and thus name frames. Thes^^ 
considerations led to ttie following suggestions: 

Have hoth a windov;. inBox and a window. outBox rather than just the 
present window. box. They are redundant in that each can be calculated 
from the other, but they ought to serve as "accelerators". It might be 
sufficient to have just an outBox and an inDims. 

Change the meaning of the normal and tiny Dimensions parameters to 
CreateWindow to refer to inBoxes rather than outBoxes (or we could add ^ 
parameter to the calling sequence to say which box the caller wanted or 
we could add a routine that converted an outBox to an inBox). .Note that 
the boxes parameters of AdjustWindowBoxProc and GrowWindow are 
similarly affected. 

Have CreateWindow NOT create the main subwindow. I think the 
primary purpose of that subwindow was to provide the information about 
the inner space of the window to the tool. That's now available via 
window. inBox. The "specialness" of the main subwindow always seemed 
a little questionable to me. This way there will be no "special" 
subwindows. 

I think all WindowPlaces ought to be relative to inBox rather than outBox. 

CreateWindow takes the window's name as a parameter. It should make 
its own copy of this string. DrawWindowNameFrame is deleted, but 
DisplayWindowFrame always does a name frame. DisplayWindow should 
always call DisplayWindowFrame. This should mean that 
DisplayWindowFrame will rarely, if ever, be called by anybody but 
DisplayWindow, 

Note that now DisplayWindowFrame will NOT change the box of any 
subwindow. 

If we wanted to retain the possibilities of windows without any frames or 
with just a border and no name, we could adopt the following (rather 
hokey) convention: if window. name = NIL, that means no frame at all; 
if the length of the name string is 0, that means just a border, but no 
name. 

Partly in order to make the creation of subwindows and windows more 
parallel and partly to help out TexTool , I suggest that the enlinking of the 
window be removed from CreateWindow. Instead, the two routines 
{En/De}LinkWindow have been added. For the same reasons, I have moved 
the place parameters from the Create routines to the Enlink routines for both 
windows and subwindows. Presumably parallel to the subwindow linking 
procedures, they will cause the display to be updated appropriately. 

I renamed the old type name "AdjustProcType" to be 

"AdjustWindowBoxProc". I choose that name since it gets called every time 

someone tries to change (adjust) the bitmap box of the window. 

There are a couple of strong reasons why I think that the refresh proc ought 
to be in the SubwindowObject rather than the WindowObject, but it would 
take too long to explain here. Note that this idea calls for some changes in 
the calling sequences to CreateWindow and CreateSubwindow. Also, I 
changed the name of the refresh proc type to be "RefreshSubwindowProc" . 

Note that I added the parameter PNRsHandle to CreateSubwindow. Since all 
subwindows should have a set of PNRs, this seems reasonable. Note, 
however, that this would blow the scheme of making PNRsObjects into 
contexts and moving the PNRs definitions to their own Defs file. 
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I ctianged the field name "backLink" in SubwindowObject* because someone 
might think it was a 1 ifik back .up the sui^window chain, i.e., to the previous 
subwindow on the chain. "windov/" seens like a better name to me. 

I changed the field name "contexts" in SubwindowObject to "contextChain" to 
conform to the sub-standards. 

Note that DestroyWindow and DestroySubwindow have had the suffix "Etc" 
added since they both destroy contexts also (contexts may now be hung off 
of windows too ~- see UiContexts). 

I added ."Put" to the names of WindowOnto{Top/Bottom} to conform to the 
convention that all such procedure names should contain a verb. Similar 
reasoning led to the adding of "Find" to WindowFromBit'mapPlace. 

I deleted all the box conversion routines because the place conversion 
routines ought to serve well enough since the Dimensions don't ever get 
converted and now you can say box. place *- Convert [box. place] whereas 
before you couldn't say [box.x, box.y] <- Convert [[box.x, box.y]]. 

Because I think they will be rarely if ever used, I suggest deleting all the 
routines that display something in a window rather than a subwindow. 
DisplayWindowFrame might have trouble, but that's the only likely 
drawback I can think of to this suggestion. 

I picked what I think will be the only commonly used display content 
routines and left them in (and changed the name of 
"ReplaceCharacterToPlacelnSubwindow" to be 
"DisplayCharacterlnSubwindow" and added the routine 

"DisplayStringlnSubwindow"). All the other display routines got coalesced 
into the three Bitblt{Pattern/Array/Character}To{Box/Place}InSubwindow 
routines, I never could figure out what the old routines did anyway. I'm 
assuming that these three routines can do everything that the 11 routines 
that they replace could do. 

Note that with the proposed set of procedures and name changes, the rather 
confusing (at least to me) use of the terms Paint, Draw, Shade, Display, 
Alter, etc. has been mostly eliminated or least made simpler and I- hope 
consistent and "intuitive". 

Maybe each window should have an additional field curDims. This field 
would be used when a user moves a window over the edge of the bitmap 
and then back again. Note that when the window goes off the edge, curBox 
gets trimmed. curDims would be used to remember what size the user really 
wanted his window to be. 
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UiMenus and UiMenuCS (Menu Comnand Specification) 

The scheme I proposH is (in .rough outline).: 

Each window has a ring of menus associated v/ith it. The number of 
items in (sone) menus may change (they're caUed "dynamic", "static" if 
the number of items is always constant). All menu items have 
"keywords". There are three types of menu items. A "leaf" item has a 
MCR (Menu Command Routine). A "switch" item has a BOOLEAN (more 
on these later). A "branch" item has a pointer to a (sub)menu. Menus 
containing one or more branch items are considered to be the root of a 
"tree" of menus. 

Most of the credit for the ideas about rings and trees of menus goes to 
Bob. 

There are three methods provided by the User Interface for specifying a 
menu command to be executed (a MCR). One may use the MenuPbkPNR 
(MPP) which displays menus while a PBK is held down and "selects** 
menu items. One may use Menu Subwindows (MSWs). The Menu 
Subwindow mechanism is a lot like the MenuPbkPNR mechanism except 
that the menus are always displayed (whether a PBK is held down op not) 
and if the subwindow is too small to display the whole menu, it may be 
scrolled. A menu command may also be specified via type-in (MCT). In 
geneneral the user types enough characters to unambiguously specify a 
keyword. 

Now here are some implementation details: 

(Almost) all windows would have exactly one. ring of menu trees (a 
window can't have more than one, but it could have zero). The 
MenuRingObject structure would be a context hanging off the window. 
A MenuRingObject has two fields: curlnst which points to the "current** 
MenuInstanceObject in the ring. Note that the **ring" is a ring of 
MenuInstanceObjects . The other field points to the "current** MenuObject 
(more on this later). 

Because dynamic menus are allowed, there must be an extra level of 
indirection provided since the actual menu items move, around as the 
array changes size. This extra level of indirection is provided by the 
MenuInstanceObjects. Menu instances are also used because there are 
expected to be a large number of instances of some menus, e.g., the 
TexTool and Window Manager menus. 

A MenuObject has fields that say whether it's a static or dynamic menu, 
count how may times this menu has been instantiated (so there won't be 
any dangling references), give the width of the widest keyword (an 
accelerator when displaying menus), name it (I think all menus ought to 
have names), and describe the whereabouts and number of the actual 
menu items (the array descriptor). 

I advocate providing for dynamic menus and menu trees (branch items) 
mostly because I think they will prove to be very useful. TexTool already 
uses both. Bob has said something about how nice it might be to select 
which font you wanted from a list (probably via branch item with a 
dynamic submenu).. Jim has indicated that his Xref tool would like to have 
different items in its menu depending on circumstances (this may be a case 
of a "variable" rather than a "dynamic" menu). 

Note: Smokey and I agreed yesterday that we would use 
MenuInstanceObjects so that some sort of dynamic menus could be 
implemented. But we also agreed that the mechanisms for dynamic menus 
would be PRIVATE (not part of the "official" or public part of the User 
Interface). 
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Add a MenuPbkPfJR. 

Add a facility for Menu Subwindows. 
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UiSelections 

Sometime soon, add various text selection PBK PNRs. -I haven 't "Specif ied any 
of these yet« 

See the discussion of the proDlem of selections above (in the "Problems" 
section) for more information. 

Sometime soon, we need to agree on a full-blown selection mechanism. 
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UlCursors 

Make the necessary, changes to StoreCursor {and SwapCursor) to implement 
the fix for the hot spot problem oiscussed above. 

Rename CursorRecord to be CursorObject (as per sub-standards). 

Define a CursorArray type. Using that type, make the code in UiCursors 
shorter by saying things like "hardCursorArrayPt *- newCursor, array ; " 
rather than using a FOR loop. 

Use the GetUniqueCursorType scheme. If this isn't done, then there must be 
a constant declared that says which values of a CursorType are pre-defined 
and which are not. 

See the attached Defs file listing for details about most of the above proposed 
changes. . 

Define lots of CursorTypes. 

Eventually, we will want to keep cursor definitions in a file and probably 
implement some sort of caching scheme. Also we'll probably want a tool to 
manipulate the file and define new cursors. 
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UiUAS 

Because User Action Streams are implenented via PORTs, there can b^ only 
Oiie User Action Stream per tool instafice (the rea.sons are too hard to explain 
here). The solution 1 propose is to put a "uas" field in Tool InstanceObjects 
and create Ur,er Action Streams relative to a tool, not a window or 
subwindow as before. 

Note that now you can have different combinations of PNRs in different 
subwindows used for the same User Action Stream. The new scheme should 
use a good deal less heap space. Also the interface is simpler. The Menu 
Command Type-in implementation will be changed similarly, except that 
you can have a MCT per window. 

See the attached listing- of UiUasDefs for the details of the new scheme. 

I would like to change the DestroyUasContextProc to just generate an ERROR 
if it ever gets called. The idea is that a tool should close the User Action 
Stream for a subwindow before it tries to destroy the subwindow. 

Sometime, DestroyUasForTool should release any local frames left around by 
the coroutines. 
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UiMisc . . ' 

See the attached listing of UiMiscDefs for details about most of the stuff 
discussed below. • 

Move stuff from TexMisc to here. -- done 

Use UiDisplay and UiFonts. 

Delete BlinkScreen (it's done as BlinkDisplay in UiDisplay now). 

Add ComputeStringWidth. ^ . 

A convenience routine that repeatedly calls ComputeCliarWidth. Perhaps 
this would be better put in UiFonts. 

Add hfopPbkPNR. •- done 

This should probably only be used by TexProcLev when one of the 
"blank" PBKs goes down (the "wiggling" bit problem) . Everybody else 
should use IgnorePbkPNR so that the user is warned that his type-in has 
been ignored via the blinking of the screen. 

Make yellow be the same "shift key" as blue for Paddle-Button chords. 

Since blue will usually be used as the menu button and since currently 
red and yellow are treated as equivalent shift keys when using the 
keyset, it makes sense to put the two "shift" buttons on the two least used 
buttons. Smokey and I will have to learn some new habits, but that's 
probably the only drawback to this proposal. 

Add Prompt, Answer, FileName, and PnrChoices types. 

The first three types are defined according to the reasoning in 
"sub-standards" so that keywords don*t have to appear in Defs files and so 
that predefined types occur as little as possible. PnrChoices is used by 
both the User Action Stream and Menu Command Type-in stuff. 

Add AskUserForParameter and delete AskUserForConf irmation. 

This is the first cut at Secondary Parameter Specification. The clients of 
this program may supply a subwindow in which the dialog will take 
place or they may say NIL in which case the Mesa window will be used. 
This routine will type the prompt in the appropriate place and then 
somehow grab the machine to receive all user actions until a 
Command-Accept is typed. The typed characters will be echoed and put 
in the Answer string supplied by the client. At least for now, it's up to 
the client to convert the Answer string to whatever form it needs. 

Add WopRef reshProc. 

This is a Ref reshSubwindowProc (see UiWindows). It could be used by 
subwindows with no "content", scroll bar subwindows for instance. 

Add TextFileRef reshProc (sometime very soon). 

This is a Ref reshSubwindowProc (see UiWindows). It could be used by 
text file and typescript subwindows for instance. Initially it will just do 
straight text files. Eventually there should be Bravo and/or Diamond file 
refresh procs (and maybe Markup, Press, SIL, etc.). , 

Add {Create/Destroy}{Vertical/Horizontal}Scrol IBarSubwindow. 

These routines will create a generalized scroll bar subwindow, using some 
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standard conventions about how they work. I have not yet ivorked out 
the calling sequence for what I have called the ScrollProc type, but it 
Shouldn't be too hard. 

Add {Create/DestroyjTypeScr iptSubwindowEtc (sometime very soon). 

This will create a subvnndow vyhich may be typed into and the typing 
will be echoed, put in a file, and selected. There will also be a veritcal 
scroll bar subwindow created (that's the reason for the Etc in the name). 
The subwindow will use the standard text selection button PNRs. 

Add {Create/Destroy}TextFileSubwindowEtc (sometime very soon). 

This will create a subwindow in which a text file will be displayed. 
There will also be a veritcal scroll bar subwindow created (that's the 
reason for the Etc in the name). The subwindow will use the standard 
text selection button PNRs. 
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UiContexts 

See the listing of UiDefs for some minor changes. 

I'm not sure that the enumeration of context types is right. 

Add facility for hanging contexts off of windows (besides subwindows). 

Note that this proposal is not reflected in any of the Defs file listings yet. 
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Librarian Interface {TLI or Tli) --* LibiDefs 

I find.it difficult to suggest improvements or discern def f iciencies 1n the 
Librarian Interface because I don't understand it very well. I think my lack of 
understanding arises primarily t.rom tv/o factors: The documentation (and 
routines and parameters) are not consistent or clear about naming things. Also 
the documentation could be better organized and give clearer explanations of 
things. (I also think there are several misleading or even erroneous statements 
in the spec). I would suggest a couple of things: 

Smokey, I very strongly urge you go through all of the Librarian , very 
carefully figure out the structure of both the code and the data, decide 
exactly what the pieces or "abstractions" are, give exactly one name to each 
thing, and very carefully define what it is exactly that each name refers to 
(such definitions should include exactly what pieces (if any) a thing is 
made up of. I urge you to write this all down. 

Such a document would be a great help to all of us in understanding the 
Librarian. Remember. that future users of the Librarian Interace are going to 
have to be able to understand the documentation or you're going to be 
constantly plagued by questions. 

I then suggest that you go through your spec and use all the defined names 
in the proper manner. This would include changing procedure and type 
names where necessary. Then you could make any necessary changes in 
the code. 

All of this naming and defining is going to have to be done sooner or later. 
I suggest that the sooner it gets done, the better the Librarian is going to 
turn out. The more people understand about your design, the more they 
can help. I hope that you'll do the naming and defining this week. The 
changing of the documentation and code could be left for a little while 
longer. 

Smokey, I hope you won*t be upset by these suggestions. They are just 
some advice from me to be taken for what its worth. I really do feel that 
following these suggestions will lead to a better "Development Environment". 

The Librarian is so central to our whole project that I think it is 
particularly important that it gets done as well as we can possibly do it, and 
I think having more people able to make informed suggestions about it 
would help. 

LibiDefs 

Remove TimeDefs from the directory. It's not referenced. 

Partly because the two modules of the Interface will now be in the main 
binding path, but mostly because I don't think it was a good idea to start 
with, I suggest you delete the, interface vectors. Note that those things take 
up a lot of extra heap space. Note also that their usefulness will be mostly 
gone when the new binding scheme happens. 

LibjectLoader 

Move all this code to Telnit. 

LibiObjects 

Remove SysDefs and InlineDefs from the directory. They're not referenced 
and SysDefs. xm is taking up (unnecessary) space on my disk. 

It's of course necessary to use the Pup interface vector, but I think you 
ought not to use the Mesa vector. 

Write a "real" LibjectContent{File/Stream}. 
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Implement Snapshots (maybe this only gets done in the Librarian Server?). 

L i b i P r p L i s t s 

The four GetProperty- routines might be coalesced into one. 

The Make{Empty/String/Record}Pair routines don't seem very useful to me. 
Wouldn't constructors work as well? 

It's of course necessary to use the Pup interface vector, but I think you 
ought not to use the Mesa vector. 

I would suggest that you seriously consider using "dynamic" property lists 
(roughly analagous to dynamic menus). Then user programs would never 
have to worry or guess at what size to allocate. Code for expanding or 
contracting property lists would only have to be written once. The 
BundleOfBits routines would go away, as would the PropertyListFull 
SIGNAL. I would then suggest that probably ALL storage allocation and 
freeing could be put in the Librarian Interface and no user program would' 
have to worry about it. 

Eventually, there should be a way to "register'* new property numbers. 
Perhaps by having something analagous to GetUniqueContextType that 
would live in the Server. 
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HFO Interface (TFi or Tfl) ~- FifoiDefs 

1 have a few more very minor suggested changes. I've noted them on Vjy 
latest copy of the functional spec. 
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Pup Package -- PupDefs 

Vie haven't loaded the PIP part of tho package yet. 

There are dangling referencer^ in the flesa interface vector. There'll be more 
as we throw away more pieces of the Mesa Runtime System. It's a crock! Don't 
use it! 
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-- File: UiDefs.mesa; Last modified by: Parsley, 24 July 1977 
DIRECTORY TexDefs: FROM •'TexDefs"; 

UiDefs: DEFINITIONS = BEGIN 

-- Coords, Dimensions, Places, and Boxes 

Coord: TYPE = INTEGER; 

Coords: TYPE = RECORD [x, y: Coord]; 

Dimension: TYPE = CARDINAL;. 

Dimensions: TYPE = RECORD [w, h: Dimension]; 



ScreenPlace: TYPE = RECORD [x, y 
BitmapPlace: TYPE = RECORD [x. y 
WindowPlace: TYPE = RECORD [x, y 



Coord]; 
Coord]; 
Coord]; 



Su.bwindowPlace: TYPE = RECORD [x, y: Coord]; 

ScreenBox: TYPE = RECORD [place: ScreenPlace. dims: Dimensions]; 

BitmapBox: TYPE = RECORD [place: BitmapPlace, dims: Dimensions]; 

WindowBox: TYPE = RECORD [place: WindowPlace, dims: Dimensions]; 

SubwindowBox: TYPE - RECORD [place: SubwindowPlace. dims: Dimensions]; 

- Windows 

WindowObject: TYPE = RECORD [ 

link: PRIVATE WindowHandle, 

subwindowChain: SubwindowHandle, 

inBox: BitmapBox, 

outBox: BitmapBox, 

adjustProc: AdjustWindowBoxProc, 

name: WindowName, 

tinyDims: Dimensions, 

normalDims: Dimensions ]: 
WindowHandle: TYPE = POINTER TO WindowObject; 

AdjustWindowBoxProc: TYPE = PROCEDURE 

[WindowHandle, BitmapBox] RETURNS [BitmapBox]; 

WindowName: TYPE = STRING; 

- Subwindows 

SubwindowObject: TYPE = RECORD [ 

link: SubwindowHandle, 

window: WindowHandle, 

box: WindowBox, 

pnrs: PNRsHandle, 

refreshProc: Ref reshSubwindowProc, 

entered; PRIVATE BOOLEAN, 

contextChain: PRIVATE ContextHandle ]; 
SubwindowHandle: TYPE = POINTER TO SubwindowObject; 

RefreshSubwindowProc: TYPE = PROCEDURE 

[SubwindowHandle, SubwindowBox, Ref reshSequencer] RETURNS [SubwindowBox]; 
RefreshSequencer: TYPE = RECORD [first, last: BOOLEAN]; * • 

- PNRs 

PNRsObject: TYPE = RECORD [ . 
cursorPNR: Cursor PnrType, 
keysetPNR: PbkPnrType. 
keyboardPNR: PbkPnrType, 
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redButtonPNR, yellowButtonPNR, blueButtonPNR: PbkPnrType ]; 
PNRsHandle: TYPE = POINTER TO PNRsObject; 

CursorPnrType: TYPE = PROCEDURE [SubwindowHandle. TexDefs.EnterEx it ];. 

PbkPnrType: TYPE = PROCEDURE 

[TexDefs.PBK, TexDef s.UpDown, SubwindowHandle, SubwindowPlace]; 

-- Contexts 

ContextObject: TYPE = RECORD [ 

link: PRIVATE ContextHandle. 

type: ContextType, 

own: OwnContextOata, 

destroyProc: DestroyContextProcType ]; 
ContextHandle: TYPE-= POINTER TO ContextObject; 

ContextType: . TYPE » {menu, met, uas, selection, textFile, typein}; 

OwnContextData: TYPE = UNSPECIFIED; 

DestroyContextProcType: TYPE = PROCEDURE [ContextHandle, SubwindowHandle]; 

END. 



UiCarsorDefs.mesa 28- JUL- 77 18:04:47 PAGE 1 






UiCursorDefs: liLs i fi f flO^iS - L'EGLri 
lypss and Constants 

CursorObject: TYPE = RECORD [ 

info: CursorlnTo, 

array: CursorArray ]; 

CursorHandle: TYPE = POINTER TO CursorObject; 

Cursorlnfo: TYPE = RECORD [ 

type: CursorType, 

hotSpot: CursorHotSpot ]; 
CursorlnfoHandTe: TYPE = POINTER TO Cursorlnfo; 

CursorArray: TYPE = ARRAY [0..16) OF WORD; 
CursorArrayP: TYPE = POINTER TO CursorArray; 

CursorType: TYPE = {testPointer , ...}: 

CursorHotSpot: TYPE = RECORD [x, y: [0..16)3; 

hardCursorArrayP: CursorArrayP = PRIVATE L00PH0LE[431B]; 

ProceduraT Interface 

GetCursorFromType: PROCEDURE [CursorType] RETURNS [CursorHandle]; 

StoreCursor: PROCEDURE [CursorHandle]; 
FetchCursor: PROCEDURE [CursorHandle]; 
SwapCursors: PROCEDURE [old, new: CursorHandle]; 

GetCurrentCursorlnfo: PROCEDURE RETURNS [CursorlnfoHandle]; 

GetUniqueCursorType: PROCEDURE RETURNS [CursorType]; 

BitmapPlaceFromCurrentCursorAndXY: PROCEDURE [TexDefs .Cursor XY] 
RETURNS [UiDefs.BitmapPlace]; 

Signals and Errors 

END. 
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FontHeight, Charl-ndth, S tringVii dtii : TYPE = CARDirJAL; 

FontHandle: lYPE = POINTER TO FontArray; 

FHptr: TYPE = POINTER TO FontHeader: 
Fptr: TYPE = POINTER TO FONT: 
FCDptr: TYPE = POINTER TO FCD; 
FAptr: TYPE = POINTER TO FontArray; 
FontArray: TYPE = ARRAY [0..256) OF FCDptr; 

FONT: TYPE = MACHINE DEPENDENT RECORD 

[ 

FHeader: FontHeader, 

FCDptrs: FontArray, -- array of self-relative pointers to 

-- FCD's. Indexed by char value. 

-- font pointer points hear! 
ExtFCDptrs: FontArray r- array of self-relative pointers to 

-- FCD's for extentions. As large an 

-- array as needed. 

3; 

FontHeader: TYPE = MACHINE DEPENDENT RECORD 

C 

maxHeight: CARDINAL, -- height of tallest char in font (scan lines) 

variableWidth: [0..1], -- IF TRUE, proportionally spaced font 

blank: [0..177B], -- not used 

maxWidth: [0..377B] -- width of widest char in font (raster units). 

3; 

FCD: TYPE = MACHINE DEPENDENT RECORD 

[ 

widthORext: [0..77777B], -- width or extention index 
hasNoExtension: BOOLEAN, -- TRUE=> no ext . ; prevf ield=width 
height: [0..377B], -- # scan lines to skip for char 
displacement: [0..377B] -- displacement back to char bitmap 

3; 

-- Font Procedures 

GetSystemFont: PUBLIC PROCEDURE 

RETURNS [FAptr, CARDINAL]; 
GetFont: PUBLIC PROCEDURE [filename: STRING] 

RETURNS [SegmentDefs.FileSegmentHandle]; 
LoadFont: PUBLIC PROCEDURE [segment: SegmentDefs.FileSegmentHandle] 

RETURNS [p: Fptr]; 
ComputeCharWidth: PUBLIC PROCEDURE 

[char: CHARACTER, font: POINTER] 

RETURNS [CARDINAL]; 

END. of ToolFontDefs 
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Uif-Uinu:U;f s: DEFINl ! lOfiS - bEGl^J 
-- lypeo and Constants 

MenuRingObject: PRIVATE TYPE "= RECORD [ 

curlnst: MenuInstanceHand! e , 

curMenu: MenuHandle]; 
MenuRingHandle: PRIVATE TYPE = POINTER TO MenuRingObject: 

MenuInstanceObject: PRIVATE TYPE = RECORD [ 

link: MenuInstanceHandle , 

menu: MenuHandle ]; 
MenuInstanceHandle: PRIVATE TYPE = POINTER TO MenuInstanceObject; 

MenuObject: PRIVATE TYPE = RECORD [ 

static: BOOLEAN, 

nin stances: [0 . . 177B], 

widestKeyword: [0..377B], 

name: MenuName, 

items: MenuItemArrayD ]; 
MenuHandle: TYPE = POINTER TO MenuObject; 

MenuName: TYPE = STRING; 

MenuItemArrayD: TYPE = DESCRIPTOR FOR ARRAY OF MenuItemObject ; 
MenuItemArrayDHandle: TYPE = POINTER TO MenuItemArrayD; 

MenuItemObject: TYPE = RECORD [ 
keyword: MenuKeyword, 

variant: SELECT COMPUTED MenuItemType FROM 
leaf => [mcrProc: McrType], 
branch => [subMenu: MenuHandle], 
switch => [onOff: BOOLEAN], 
ENDCASE ]; 
MenuItemHandle: TYPE = POINTER TO MenuItemObject; 
Menultemlndex: TYPE = CARDINAL; 

MenuItemType: TYPE = {leaf, branch, switch}; 

MenuKeyword: TYPE = STRING; 
menuKeywordBranch: CHARACTER == 't; 
menuKeywordSwitch: CHARACTER = '?; 

McrType: TYPE = PROCEDURE 

[UiDef s.SubwindowHandle, MenuHandle, Menultemlndex]; 

-- Procedural Interface 

CreateStaticMenu: PROCEDURE [MenuItemArrayD, MenuName] 

RETURNS [MenuHandle]; 
DestroyStaticMenu: PROCEDURE [MenuHandle]; 

CreateDynamicMenu: PROCEDURE [MenuName] RETURNS [MenuHandle]; 
DestroyDynamicMenu: PROCEDURE [MenuHandle]; 

' AddltemToDynamicMenu: PROCEDURE [MenuHandle, MenuItemObject]; 
DeleteltemFromDynamicMenu: PROCEDURE [MenuHandle, MenuItemHandle]; 
DeletelndexFromDynamicMenu: PROCEDURE [MenuHandle, Menultemlndex]; 
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D.js LroyMei.uKoywjrd: PHIVAIE f-ROCLUURL [[;._-nuKeywor'd] : 
AddUnuel I Ur.tloDynanii cMenu : PRiVAfi: PROCLi)UHt 

[iMenuHand le , MenuKeyword] RETURI\1S [Menui temHandle] : 
DeleteUndefltemi-romDynanicMenu: PRIVAfE PROCEDURE 

[MenuHandle, Menultemlndex] ; 
FixMenuKeywords: PRIVATE PROCEDURE 

[menu: MenuHandle, newlndex: Menultemlndex]; 
DestroyMenuRingContext: PRIVATE UiDef s .DestroyContextProcType; 

GetMenuFont: PRIVATE PROCEDURE 

RETURNS [UiFontDefs.FonlHandle, UiFontDef s . FontHeight]; 
ChangeMenuFont: PRIVATE PROCEDURE 

[UiFontDefs.FontHandle, UiFontDef s . FontHeight]; 

CreateMenuRingForWindow: PRIVATE PROCEDURE [UiDef s. Window/Handle] ; 
DestroyMenuRingFromWindow: PRIVATE PROCEDURE [UiDefs .WindowHandle] ; 

-- Signals and Errors 

MenuItemNot Found: ERROR; 
Menu I nstanceNot Found: ERROR; 
MenuKeywordsConfl ict: ERROR; 
MenuStatDynError: ERROR; 
MenuInUse: ERROR; 

END. 
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UiOt;i :s : rri'f] 'Ui[;uf 5" , 
UiM'ii-nuOers : FROM "U iMenuOef s" , 
Uil'. lo cue Fo: PROM "Uii-i i bcDef s*' . 
lODefs: FROM "iODefs": 

DEFINITIONS FROM UiMenuDefs; 

UiMenuCsDefs: DEFINITIONS = BEGIN 

-- Types and Constants 

~- Types and Constants used by more than one of MPP, MSW, MCT 

MenuMatrixDimension: PRIVATE TYPE = [0..377B); 
menuMargin: PRIVATE CARDINAL = 2; 

-- MPP's Types and Constants 

noFlip: PRIVATE CARDINAL = 16; 

-- if cursor is this close to a Menu Window, it won't flip 

~- MSW's Types and Constants 

MswObject: PRIVATE TYPE = RECORD [ -- pointed to by context. own 

scrollMenuVerticalSw, scrollMenuHorizontalSw: UiDef s .SubwindowHandle, 
nHorltems, nVerltems: MenuMatrixDimension, 
horOffset, verOffset: MenuMatrixDimension, 
variant: SELECT MswType FROM ' 

ring => [scro1 IRingSw: UiDef s .SubwindowHandle], 
tree => [rootMenu, curMenu: MenuHandle], 
ENDCASE ] 
MswHandle: PRIVATE TYPE = POINTER TO MswObject; 

MswType: PRIVATE TYPE = {tree, ring} 

-- MCT's Types and Constants 

MctObject: PRIVATE TYPE = RECORD [ ~- pointed to by mainSw. context . own 

feedBack: UiDef s .SubwindowHandle, 

pbs: TexDef s.PaddlesButtons, 

partial: STRING ]; 
MctHandle: PRIVATE TYPE = POINTER TO MctObject; 

mctPartiallnitLength: PRIVATE CARDINAL = 4; 
mctUserCA: PRIVATE CHARACTER = lODefs.ESC; 

-~ Procedural Interface 

~- Procedures used by more than one of MPP, MSW, MCT 

RefreshMSW: PRIVATE UiDef s . Ref res hSubwindowProc; 
PaintMSW: PRIVATE PROCEDURE [sw: UiDef s .SubwindowHandle, 

nHorltems, nVerltems, horOffset, verOffset: MenuMatrixDimension]; 

-~ MPP's Procedural Interface 
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-- !':..[':. Procdcuirai interfoCj 

Creatc^riCtForWirpJow: PROCEDuiVc 

[U iDef s . W i fuJowHafUile , Uii)ef s . Subvri ndowHandle] ; 

-- subwindow is used for feedback; if NIL. use "system" window 
Destroy?vlctFroniWindow: PROCEDURE [UiDef s . Wi ndowHandl e] ; 

OpenMctForWindow: PROCEDURE 

[UiDef s .WindowHandle, UiMiscDef s . PnrChoices] ; 
OpenMctForSubwindow: PROCEDURE 

[UiDef s .SubviindowHandTe, UiMiscDef s .PnrChoices]; 
CloseMctForWindow: PROCEDURE [UiDef s .WindowHandle] ; 
CloseMctForSubwindow: PROCEDURE [UiDef s .SubwindowHandle] ; 

- Signals and Errors 

SubwindowAlreadylsMsw: SIGNAL; 
MswNotLargeEnough: SIGNAL; 
MswTreeMenuNotlnRing: ERROR; 
UlegalMsw: ERROR; 

WindowAlreadyHasMCT: ERROR; 
II legal MctFeedBackSubwindow: ERROR; 
WindowHasNoMCT: ERROR; 
InvalidPNRsForMCT: ERROR; 



END. 
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UiMiscDefs: DEFiniflOf^S - btGirj 

~- ly pes and Constants 

KeyCode: TYPE = [0. ,177B]: 

KeyDescription: lYPE = RECORD [ 
useLock: BOOLEAN, 
shiftCode: KeyCode, 
normalCode: KeyCode ]: 

KeysDescpiptionTable: TYPE = ARRAY TexDef s .Key OF KeyDescription; 

PaddlesTransString: TYPE = STRING; 

ButtonsTransTable: TYPE = ARRAY [0..8) OF CHARACTER; 
ButtonsShiftTable: TYPE = ARRAY [0..8) OF CARDINAL; 

Prompt, Answer, FileName: TYPE = STRING 

PnrChoices: TYPE = RECORD [keyboard, keyset, red, yellow, blue: BOOLEAN]; 

-"■ Procedural Interface 

IgnorePbkPNR: UiDef s .PbkPnrType; 
NopPbkPNR: UiDef s . PbkPnrType ; 
NopCursorPNR: UiDef s .Curs or PnrType ; 

NopRef reshProc: UiDef s . Re f res hSubw in dowP roc; 
TextFileRef reshProc: UiDef s . RefreshSubwindowProc; 

CreateVertical Scroll BarSubwindow: PROCEDURE 

[UiDefs.SubwindowHandle, ScrollProc] RETURNS [UiDef s .SubwindowHandle] ; 
CreateHorizontal Scroll BarSubwindow: PROCEDURE 

[UiDefs.SubwindowHandle, ScrollProc] RETURNS [UiDefs.SubwindowHandle]; 
DestroySc roll BarSubwindow: PROCEDURE [UiDefs.SubwindowHandle]; 
ScrollProc: TYPE = PROCEDURE [UiDefs.SubwindowHandle--??--]; 

CreateTextFileSubwindowEtc: PROCEDURE 

[UiDef s .WindowBox, StreamDef s .DiskHand.le] 

RETURNS [UiDefs.SubwindowHandle]; 
DestroyTextFileSubwindowEtc: PROCEDURE [UiDefs.SubwindowHandle]; 

CreateTypelnSubwindowEtc: PROCEDURE 

[UiDef s .WindowBox, FileName] 

RETURNS [UiDefs.SubwindowHandle]; 
DestroyTypelnSubwindowEtc: PROCEDURE [UiDefs.SubwindowHandle]; 

PostMessage: PROCEDURE [STRING]; 

PostMessageZ: PROCEDURE [STRING, STRING]; " • 

PostMsgCont: PROCEDURE [STRING]; 

AskUserForParametert PROCEDURE [Prompt, Answer, UiDefs.SubwindowHandle]; 

SetStateOfPBKs: PROCEDURE [TexDef s . PBKsP, TexDefs.PBK, TexDef s .DownUp] ; 
SetStateOfPaddlesButtons: PROCEDURE 

[TexDefs.PaddlesButtonsP, TexDefs.PBK, TexDef s .DownUp]'; 
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Kif ceS *.r'i ngi ov/ei^ : rr'jLiuckl [iu: STRINb. ii^Oi-i: SlKiivGj: 

T r a n s ! <i I e P ad d 1 e s I n t oC: ii a r : 

PROOLlJiJl^b [FexDefs. Paddles. lexOofs . Buttons] RETURfiS [CHARACTtR]: 
Trans 1 ateBultons IntoChar : 

PROCEDURE [TexDefs. Buttons] RETURf^sS [CHARACTER]; 
T r an slateKey IntoChar I 

PROCEDURE [TexDefs. Key, TexDefs .KeysP] RETURNS [CHARACTER]; 

-- Signals and Errors 
END. 
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UiUasDefs: DEFIfoillOfJS = BLGliJ 
~- Types and Constants 

UasObJect: PRIVATE TYPE = RECORD [ ~- is pointed to by fool InstanceObject . uas 

pbs : TexDef s .PaddlesButtons, 

getUasCharP: GetUasCharPortP, 

putUasCharP: PutUasCharPortP, 

portBlock: UasPortBlock ] ; 
UasHandle: PRIVATE TYPE = POINTER TO UasObject; 

GetUasCharPortType: TYPE = PORT RETURNS [CHARACTER]; 
GetUasCharPortP: TYPE = POINTER TO GetUasCharPortType; 
PutUasCharPortType: PRIVATE TYPE = PORT [CHARACTER]; 
PutUasCharPortP: PRIVATE TYPE = POINTER TO PutUasCharPortType; 
UasPortBlock: PRIVATE TYPE = ARRAY [O^S] OF UNSPECIFIED; 

two ports get stored here; 

the extra words allow the beginning addresses to end in 2B 

Tool: TYPE = TexManipTool sDef s .Tool InstanceHandle; 

-~ Procedural Interface 

CreateUasForTool : PROCEDURE [Tool]; 
DestroyUasFromTool : PROCEDURE [Tool]; 

OpenUasForWindow: PROCEDURE 

[Tool , UiDef s . WindowHandle , UiMiscDef s. Pnr Choices] 

RETURNS [GetUasCharPortP]; 
OpenUasForSubwindow: PROCEDURE 

[Tool, UiDef s .SubwindowHandle, UiMiscDef s . PnrChoices] 

RETURNS [GetUasCharPortP]: 
CloseUasForWindow: PROCEDURE [UiDef s .WindowHandle] ; 
CloseUasForSubwindow: PROCEDURE [UiDef s , SubwindowHandle] ; 

~- Signals and Errors 

ToolAlreadyHasUAS: ERROR; 
ToolHasNoUAS: ERROR; 
Inval idPNRsForUAS: ERROR; 

END. 
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UivJindowDers: DEFlfilTIONS = BEGIH 

Types and Constants 

-- Most of the definitions of UiDefs would normally occur here 

IntegerArrayD: TYPE - DESCRIPTOR FOR ARRAY OF INTEGER; 

Roundedness: TYPE = [0..4]; 

SubwindowPlaceArrayD: TYPE = DESCRIPTOR FOR ARRAY OF SubwindowPlace; 

BitbltPattern: TYPE = ARRAY [0.,4) OF WORD; 

BitbltArrayP: TYPE = POINTER; 

WordsPerLine: TYPE = CARDINAL; 

Procedural Interface 

-- Basic procedures; deal with [sub]windows as a whole, not contents of 

CreateWindowEtc: PROCEDURE [ 

name: WindowName, 

normal, tiny: Dimensions, 

adjustProc: AdjustWindowBoxProc] 

RETURNS [WindowHandle, SubwindowHandle] ; 
DestroyWindowEtc: PROCEDURE [WindowHandle]; 

Nop AdjustWindowBoxProc: AdjustWindowBoxProc; 

EnlinkWindow: PROCEDURE [WindowHandle, BitmapPlace]; 
DelinkWindow: PROCEDURE [WindowHandle]; 

CreateSubwindow: PROCEDURE [Dimensions, PNRsHandle, Ref reshSubwindowProc] 

RETURNS [SubwindowHandle]; 
DestroySubwindowEtc: PROCEDURE [SubwindowHandle]; 

NopRef reshSubwindowProc: Ref reshSubwindowProc; 

EnlinkSubwindow: PROCEDURE 

[WindowHandle, SubwindowHandle, WindowPl ace]; 
DelinkSubwindow: PROCEDURE [SubwindowHandle]; 

GrowWindow: PROCEDURE [WindowHandle, BitmapBox]; 

MoveWindow: PROCEDURE [WindowHandle, BitmapPlace]; 

MoveWindowContinuous : PROCEDURE [WindowHandle, MoveContinuousProc] ; 
MoveContinuousProc: TYPE = PROCEDURE 

[WindowHandle] RETURNS [BOOLEAN, BitmapPlace]; 

PutWindowOntoTop: PROCEDURE [WindowHandle]; ' * 

PutWindowOntoBottom: PROCEDURE [WindowHandle]; 

-- Conversion procedures 

FindWindowFromBitmapPlace: PROCEDURE [BitmapPlace] 
RETURNS [WindowHandle]; 
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[SubvyindowHand le, Subw i ndovPI ace] Rt lUIUJS [B i tmapPI ace] ; 

WindowPlaceFroniBilmapPlace: PROCEDURE 

[WindowHandle, BilmapP 1 ace] RETURNS [Wi ndowPl ace] : 
WindowPlaceFromSubwindowPlace: PROCEDURE 

[SubwindoviHandle , Subwindov/P1 ace] RETURNS [WindowPlace] ; 

Su bw i ndowPl ace FromWindowP lace: PROCEDURE 

[SubwindowHandle, WindowPlace] RETURNS [SubwindowPlace] ; 

- Miscellaneous display procedures 

DisplayWindow: PROCEDURE [WindowHandle]; 

DisplayWindowFrame: PROCEDURE [WindowHandle]; 

MoveBoxInSubwindow: PROCEDURE 

[SubwindowHandle, SubwindowBox , SubwindowPlace]; 

TrimSubwindowBox: PROCEDURE [SubwindowHandle, SubwindowBox] 
RETURNS [SubwindowBox]; 

- Content procedures; display bits inside of subwindows 

DisplayCharacterlnSubwindow: PROCEDURE 

[SubwindowHandle, SubwindowPlace, CHARACTER, UiFontDef s . FontHandle] 

RETURNS [SubwindowPlace]; 
DisplayStringlnSubwindow: PROCEDURE 

[SubwindowHandle, SubwindowPlace, STRING, UiFontDef s..FontHandle] 

RETURNS [SubwindowPlace]; 

WhitenBoxInSubwindow: PROCEDURE [SubwindowHandle, SubwindowBox]; 
BlackenBoxInSubwindow: PROCEDURE [SubwindowHandle, SubwindowBox]; 
InvertBoxInSubwindow: PROCEDURE [SubwindowHandle, SubwindowBox] ; 

BitbltPatternToBoxInSubwindow: PROCEDURE 

[SubwindowHandle, SubwindowBox, Bi tbl tPattern , 
UiDisplayDef s .BbSourceType, UiDisplayDef s . BbOperation]; 

BitbltArrayToBoxInSubwindow: PROCEDURE 

[SubwindowHandle, SubwindowBox, Bi tbl tArrayP, WordsPerLine, 
UiDisplayDef s .BbSourceType, UiDisplayDef s .BbOperation] ; 

BitbltCharacterToPlacelnSubwindow: PROCEDURE 

[SubwindowHandle, SubwindowPlace, CHARACTER, UiFontDef s . FontHandle, 
UiDisplayDef s .BbSourceType, UiDisplayDef s .BbOperation] 
RETURNS [SubwindowPlace]; 

- Graphic content procedures; draw bits inside of subwindows 

DrawDi agonal Of SubwindowBox: PROCEDURE 
[SubwindowHandle, SubwindowBox]; 

Dr^wRectil inearCurvelnSubwindow: PROCEDURE 
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[UiDwMJIdyi^ers.BhPlr J: 

Signals anci Errors 

Windowf^jottn linked: ERROR; 
ViindowAlreadytnl inked: ERROR; 
Subv/indowNotEnl inked: ERROR; 
Subv/indov^Al ready Enl inked: ERROR; 



END. 



